Utils

Overview

API utility functions. Utilities for general operations to simplify methods or for items that are not accessible through API objects.

  • From version: 2020.20

Methods

clearChips

clearChips ( chipsToClear : Chip []): void

Clears all elements of the specified chips from visuals that have a data-interaction connection with the custom visual. It will only clear the hierarchical selections that are injected into the targeted visuals. It will not remove the hierarchy from any other aspect of the targeted visual. 

cvApi2.utils.clearChips(chipsToClear);

Parameters

  • chipsToClear:Chip[]

    list of chips whose elements should be cleared.

Returns void

deselectAllElements

deselectAllElements (): void

Used to deselect all elements, resulting in an empty selection state. Used to respond to user interactions with the visual. 

cvApi2.utils.deselectAllElements();
Returns void

getAllChips

getAllChips (): Chip []

Gets all the deployed chips from all the active Dropzones. 

Const AllChips = cvApi2.utils.getAllChips();
Returns Chip[]

All the deployed chips from all the active Dropzones.

getChip

getChip ( chipUniqueName : string): Chip

Returns a Chip by its unique name. Use this function when quick access to a particular Chip is needed. 

const chip = cvApi2.utils.getChip(chipUniqueName);

Parameters

  • chipUniqueName:string

    The chip unique id.

Returns Chip

Chip by its unique name.

getDropzone

getDropzone ( dropZoneType : DropZoneType ): Dropzone

Returns the matching Dropzone object using the DropZoneType. Null is returned if the drop zone is not being used in the visual. Use this function when quick access to a particular Dropzone is needed. 

const xValuesDropZone = cvApi2.utils.getDropzone(cvApi2.enums.DropZoneType.XAxis);

Parameters

  • dropZoneType:DropZoneType

    Enum that represent the drop zone uniquely.

Returns Dropzone

Matching Dropzone object using the DropZoneType.

inject

inject ( selectionsToAdd : Selection , selectionsToRemove ? : Selection , chipsToClear ? : Chip []): void

Injects or removes selections in visuals that have a data-interaction connection with the custom visual. This function allows you to add new selections, remove existing ones, and clear specific chips. It replicates the behavior of the built-in Visual data-interaction system. It perform all 3 actions in a singular transaction - member selection, member deselection and entire hierarchy/chip clearance. Selections replace existing selections, they are NOT additive. 

cvApi2.utils.inject(selectionsToAdd, selectionsToRemove, chipsToClear);

Parameters

  • selectionsToAdd:Selection

    The selection object containing datapoints and/or elements that should be added to the connected visuals.

  • selectionsToRemove?:Selection

    (Optional) A selection object defining datapoints and/or elements that should be removed from the connected visuals.

  • chipsToClear?:Chip[]

    (Optional) list of chips whose elements should be cleared.

Returns void

selectDatapoints

selectDatapoints ( datapoints : Datapoint []): void

Used to set selection state on a collection of datapoints. Used to respond to user interactions with the visual. 

cvApi2.utils.selectDatapoints(datapoints);

Parameters

Returns void

selectElements

selectElements ( elements : Element []): void

Used to set selection state on a collection of member elements. Used to respond to user interactions with the visual. 

cvApi2.utils.selectElements(elements);

Parameters

  • elements:Element[]

    The elements we want to select.

Returns void

Notes

The following functions have overlapping functionality. However, each has a specific nuance.

  • The "Inject" function will perform 3 actions in a single transaction - member selection, member deselection and entire hierarchy/chip clearance. Member selections replace existing selections, they are NOT additive.
  • The "ClearChips" method will only clear the hierarchical selections that are injected into the targeted visuals. It will not remove the hierarchy from any other aspect of the targeted visual.
  • The "SelectElements" and "SelectDatapoints" are related to the "Inject" function - but only handle member selections, without deselection operations.